home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tcl / Eval.man < prev    next >
Encoding:
Text File  |  1992-08-21  |  8.0 KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_Eval              C Library Procedures               Tcl_Eval
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval  -  exe-
  12.      cute Tcl commands
  13.  
  14. SSYYNNOOPPSSIISS
  15.      ##iinncclluuddee <<ttccll..hh>>
  16.  
  17.      int
  18.      TTccll__EEvvaall(_i_n_t_e_r_p, _c_m_d, _f_l_a_g_s, _t_e_r_m_P_t_r)
  19.  
  20.      int
  21.      TTccll__VVaarrEEvvaall(_i_n_t_e_r_p, _s_t_r_i_n_g, _s_t_r_i_n_g, ... ((cchhaarr **)) NNUULLLL)
  22.  
  23.      int
  24.      TTccll__EEvvaallFFiillee(_i_n_t_e_r_p, _f_i_l_e_N_a_m_e)
  25.  
  26.      int                                                           |
  27.      TTccll__GGlloobbaallEEvvaall(_i_n_t_e_r_p, _c_m_d)                                   |
  28.  
  29. AARRGGUUMMEENNTTSS
  30.      Tcl_Interp   *_i_n_t_e_r_p      (in)      Interpreter in which  to
  31.                                          execute   the   command.
  32.                                          String  result  will  be
  33.                                          stored     in    _i_n_t_e_r_p-
  34.                                          >_r_e_s_u_l_t.
  35.  
  36.      char         *_c_m_d         (in)      Command (or sequence  of
  37.                                          commands) to execute.
  38.  
  39.      int          _f_l_a_g_s        (in)      Either  TTCCLL__BBRRAACCKKEETT__TTEERRMM
  40.                                          or   0.    If   0,  then
  41.                                          TTccll__EEvvaall  will   process
  42.                                          commands  from _c_m_d until
  43.                                          it  reaches   the   null
  44.                                          character  at the end of
  45.                                          the     string.       If
  46.                                          TTCCLL__BBRRAACCKKEETT__TTEERRMM,   then
  47.                                          TTccll__EEvvaall  will   process
  48.                                          comands  from  _c_m_d until
  49.                                          either it reaches a null
  50.                                          character      or     it
  51.                                          encounters    a    close
  52.                                          bracket    that    isn't
  53.                                          backslashed or  enclosed
  54.                                          in   braces,   at  which
  55.                                          point  it  will  return.
  56.                                          Under normal conditions,
  57.                                          _f_l_a_g_s should be 0.
  58.  
  59.      char         **_t_e_r_m_P_t_r    (out)     If _t_e_r_m_P_t_r is  non-NULL,
  60.  
  61.  
  62.  
  63. Sprite v1.0                                                     1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_Eval              C Library Procedures               Tcl_Eval
  71.  
  72.  
  73.  
  74.                                          TTccll__EEvvaall     fills    in
  75.                                          *_t_e_r_m_P_t_r    with     the
  76.                                          address of the character
  77.                                          just after the last  one
  78.                                          in the last command suc-
  79.                                          cessfully executed (nor-
  80.                                          mally the null character
  81.                                          at the end of _c_m_d).   If
  82.                                          an  error  occurs in the
  83.                                          first  command  in  _c_m_d,
  84.                                          then  *_t_e_r_m_P_t_r  will  be
  85.                                          set to _c_m_d.
  86.  
  87.      char         *_s_t_r_i_n_g      (in)      String forming  part  of
  88.                                          Tcl command.
  89.  
  90.      char         *_f_i_l_e_N_a_m_e    (in)      Name of file  containing
  91.                                          Tcl command string.
  92. _________________________________________________________________
  93.  
  94.  
  95. DDEESSCCRRIIPPTTIIOONN
  96.      All four of these procedures execute Tcl commands.  TTccll__EEvvaall
  97.      is the core procedure:  it parses commands from _c_m_d and exe-
  98.      cutes them in order until either an error occurs or TTccll__EEvvaall
  99.      reaches  a  terminating character (']' or '\0', depending on
  100.      the value of _f_l_a_g_s).  The return value from TTccll__EEvvaall is  one
  101.      of  the  Tcl  return  codes  TTCCLL__OOKK,  TTCCLL__EERRRROORR, TTCCLL__RREETTUURRNN,
  102.      TTCCLL__BBRREEAAKK, or TTCCLL__CCOONNTTIINNUUEE, and _i_n_t_e_r_p->_r_e_s_u_l_t will point to
  103.      a  string with additional information (result value or error
  104.      message).  This return information corresponds to  the  last
  105.      command executed from _c_m_d.
  106.  
  107.      TTccll__VVaarrEEvvaall takes any number  of  string  arguments  of  any
  108.      length,  concatenates  them into a single string, then calls
  109.      TTccll__EEvvaall to execute  that  string  as  a  Tcl  command.   It
  110.      returns  the result of the command and also modifies _i_n_t_e_r_p-
  111.      >_r_e_s_u_l_t in the usual fashion for  Tcl  commands.   The  last
  112.      argument  to TTccll__VVaarrEEvvaall must be NULL to indicate the end of
  113.      arguments.
  114.  
  115.      TTccll__EEvvaallFFiillee reads the file given by _f_i_l_e_N_a_m_e and  evaluates
  116.      its  contents  as  a  Tcl  command  by calling TTccll__EEvvaall.  It
  117.      returns a standard Tcl result that reflects  the  result  of
  118.      evaluating  the  file.   If the file couldn't be read then a
  119.      Tcl error is returned to describe why the file  couldn't  be
  120.      read.
  121.  
  122.      TTccll__GGlloobbaallEEvvaall  is  similar  to  TTccll__EEvvaall  except  that   it  |
  123.      processes  the command at global level.  This means that the  |
  124.      variable context for the command consists  of  global  vari-  |
  125.      ables  only  (it  ignores any Tcl procedure that is active).  |
  126.  
  127.  
  128.  
  129. Sprite v1.0                                                     2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_Eval              C Library Procedures               Tcl_Eval
  137.  
  138.  
  139.  
  140.      This produces an effect similar to the Tcl command ``uupplleevveell  |
  141.      00''.
  142.  
  143.      During the processing of a Tcl command it is legal  to  make
  144.      nested  calls to evaluate other commands (this is how condi-
  145.      tionals, loops, and procedures are implemented).  If a  code
  146.      other than TTCCLL__OOKK is returned from a nested TTccll__EEvvaall invoca-
  147.      tion, then the caller should  normally  return  immediately,
  148.      passing  that same return code back to its caller, and so on
  149.      until the top-level application is reached.  A few commands,
  150.      like   ffoorr,  will  check  for  certain  return  codes,  like
  151.      TTCCLL__BBRREEAAKK  and  TTCCLL__CCOONNTTIINNUUEE,  and  process  them  specially
  152.      without returning.
  153.  
  154.      TTccll__EEvvaall keeps track of how many nested Tcl_Eval invocations
  155.      are  in  progress  for  _i_n_t_e_r_p.   If  a  code of TTCCLL__RREETTUURRNN,
  156.      TTCCLL__BBRREEAAKK, or TTCCLL__CCOONNTTIINNUUEE is about to be returned from  the
  157.      topmost  TTccll__EEvvaall  invocation for _i_n_t_e_r_p, then TTccll__EEvvaall con-
  158.      verts the return code to TTCCLL__EERRRROORR and  sets  _i_n_t_e_r_p->_r_e_s_u_l_t
  159.      to  point  to  an  error message indicating that the rreettuurrnn,
  160.      bbrreeaakk, or ccoonnttiinnuuee command was invoked in  an  inappropriate
  161.      place.   This means that top-level applications should never
  162.      see a  return  code  from  TTccll__EEvvaall  other  then  TTCCLL__OOKK  or
  163.      TTCCLL__EERRRROORR.
  164.  
  165.  
  166. KKEEYYWWOORRDDSS
  167.      command, execute, file, global, interpreter, variable
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Sprite v1.0                                                     3
  196.  
  197.  
  198.  
  199.